home *** CD-ROM | disk | FTP | other *** search
/ Cream of the Crop 25 / Cream of the Crop 25.iso / os2 / srefv12i.zip / adv_opts.doc < prev    next >
Text File  |  1997-03-09  |  7KB  |  192 lines
  1. 7 Mar 1997.
  2. Description of SRE-Filter's SEL-specific "advanced options"
  3.  
  4. 1) Introduction
  5.  
  6. The SEL-specific advanced-options provide a set of less-frequently needed,
  7. "advanced-options" to the ambitious webmaster.
  8. These advanced-options include:
  9.  * execution of "mid-filter" procedures,
  10.  * customization of response headers 
  11.  * suppression of specific server side includes.
  12.  * in the future, additional features may be added.
  13.  
  14.  
  15. 2) Specifying an advanced-options file.
  16.  
  17. To use these advanced-options, you need to specify a SEL-specfic
  18. "advanced-options file".  As with other SEL-specific controls, this is 
  19. done by modifying ALL_FILE.CTL (the ACCESS_CONTROL_FILE) -- either by 
  20. hand, or with the intermediate-mode configurator.
  21.  
  22.    Note:there is NO global (default) advanced-options file.
  23.  
  24. Advanced-options files should be located in, or under, the DATA\
  25. subdirectory of your GoServe working directory (actually, it will be in
  26. or under the SRE-Filter WORKDATA_DIR directory).  Thus, when specifying 
  27. (in ALL_FILE.CTL) an advanced-options file, you should NOT use a fully 
  28. qualified name.
  29.  
  30. For example, assuming that your SRE-FIlter "WORKDATA_DIR" directory is
  31. D:\GOSERVE\DATA, the following entry in ALL_FILE.CTL:
  32.    /SAMPLES/* *   ,     ,  MYREALM  ,   , ADV_OPT.CTL
  33. tells SRE-Filter to use D:\GOSERVE\DATA\ADV_OPT.CTL
  34.  
  35.  
  36.  
  37. 3) The advanced options
  38.  
  39. Currently, there are three sets of options that may be set in the
  40. advanced options file:
  41.  
  42.   1) EXEC commands  -- execute an external REXX procedure.
  43.   2) HEADER and RESPONSE directives -- specify a custom response header
  44.   3) SSI_suppression directives -- suppress specific SSI actions.
  45.  
  46. Note that each of these entries should appear on a single line (lines 
  47. beginning with a ; are comments).  The following documents how to
  48. use these options.  We also recommend perusing the ADV_OPTS.CTL and
  49. ADV_OPTS.CMD sample files.
  50.  
  51.  
  52. 3a) EXEC Commands
  53.  
  54. EXEC entries are used to execute external REXX procedures.  This execution 
  55. occurs just before the "verb is processed", and after all "selector
  56. modifications/redirections" and "access control checks."
  57.  
  58.     In a sense, the EXEC commands can be thought of as "mid-filter" hook,
  59.     in between SRE-Filter's (optional) pre- and post- filters.
  60.  
  61. Example:
  62.   EXEC ADV_OPTS.CMD  Hello from job 1.
  63.  
  64. In this example, ADV_OPTS.CMD should be in the GoServe working directory.
  65.  
  66. Note that ADV_OPTS will be sent a set of variables:
  67.  ARGUMENT:
  68.      The "argument" following the procedure-file name.  This may contain
  69.      commas (a comma containing ARGUMENT does NOT result in multiple
  70.      arguments being sent to the called procedure).
  71.      In the above example, ARGUMENT would be "Hello from job 1." (without
  72.      the quotes).
  73.  SOURCE:
  74.     The GoServe "source" line
  75.  REQUEST:
  76.     The GoServe request line
  77.  SEL:
  78.    The (SRE-Filter) modified selector
  79. VERBOSE:
  80.    The SRE-Filter VERBOSE parameter
  81. SERVERNAME:
  82.    The name of the server processing this request (might be an alias)
  83. HOST_NICKNAME:
  84.    SRE-Filter "host nickname" for the server processing this request
  85. DATA_DIRECTORY:
  86.    The default data directory (might be servername dependent)
  87. HOME_DIRECTORY:
  88.    The GoServe working directory
  89. TEMP_DIRECTORY:
  90.    The SRE-Filter TEMPDATA_DIR "temporary files" directory
  91.  
  92. These external procedures MAY issue GoServe completion codes. If they do, 
  93. they should return
  94.   status_code bytes_sent
  95. (i.e.; 200 15122)
  96. If they do not, they should return a 0.
  97. All other returns are ignored.
  98.  
  99. Note that ADV_OPTS.CMD contains a simple example of such an external
  100. procedure.
  101.  
  102.  
  103. 3b) HEADER and RESPONSE directives.
  104.  
  105. You can include HEADER and RESPONSE entries -- they will be sent almost
  106. verbatim to GoServe  
  107.  
  108. This response header customization is only available for GET and HEAD
  109. requests that invoke a file transferal (including HTML documents
  110. with server side includes).
  111.     That is, for "server side processing" requests (such as CGI-BIN
  112.     scripts, SRE-Filter add-ons, PUT and DELETE requests, and imagemaps)
  113.     HEADER and RESPONSE entries will NOT be used.
  114.  
  115. As a convenience, SRE-Filter will perform a few substitutions on HEADER
  116. and RESPONSE entries:
  117.   $GMT : The current  GMT day, date and time.
  118.   $SERVERNAME: The "server name" of the server processing this request
  119.   $SIZE: The number of bytes to be sent
  120.   $CODE: The status code (almost always 200)
  121.  
  122. Examples:
  123.   header add X-Webmaster-Name: Daniel Platypus
  124.   header add X-comment:  X- headers are created by SRE-Filter
  125.   header add X-Our-server: $servername
  126.   header add X-Size-1: this is $size size
  127.   header add X-Code-1: this is $code code
  128.  
  129. Notes
  130.  *  This customization is akin to ICS's "meta information".
  131.  *  See GOSERVE.DOC for a description of the HEADER and RESPONSE GoServe 
  132.     directives.
  133.  
  134. 3c) Server Side Include Suppression
  135.  
  136. Although you can suppress all server side includes (either for all documents,
  137. or on a SEL-specific basis), you may wish to only suppress a select set of
  138. these includes. In particular, you may wish to supress HEADERS and FOOTERS
  139. for a portion of  your HTML documents.  This can be easily done with
  140. the various server side include suppression options.
  141.  
  142. The available options are:
  143.   ssi_no_cache     : suppress caching (similar to a <!-- CACHE NO -->
  144.                      keyphrase)
  145.   ssi_no_header    : Do NOT include HEADERS lines
  146.   ssi_no_footer    : Do NOT include FOOTERS lines
  147.   ssi_no_replace   : Do NOT process <!-- REPLACE varname --> keyphrases
  148.   ssi_no_include   : Do NOT process <!-- INCLUDE filename --> keyphrases
  149.   ssi_no_option    : Do NOT process <!-- OPTION n --> keyphrases
  150.   ssi_no_interpret : Do NOT process <!-- INTERPRET FILE filename --> or
  151.                      <!-- INTERPRET CODE  xxx ;yyy --> keyphrases.
  152.   ssi_no_select    : Do NOT process <!-- SELECT xxx --> ... <!-- SELECT END -->
  153.                      keyphrases
  154.   ssi_no_#filestat : Do NOT process <!-- #FLASTMOD ... --> or <!-- #FSIZE ... -->
  155.                      keyphrases
  156.   ssi_no_#config   : Do NOT process <!-- #CONFIG ... --> keyphrases
  157.   ssi_no_#echo     : Do NOT process <!-- #ECHO ... --> keyphrases
  158.   ssi_no_#include  : Do NOT process <!-- #INCLUDE ... --> keyphrases
  159.   ssi_no_#exec     : Do NOT process <!-- #EXEC ... --> keyphrases
  160.  
  161. Note that these options should appear one-per-line.
  162.  
  163. Examples:
  164.   ssi_no_cache
  165.   ssi_no_header
  166.   ssi_no_footer
  167.   ssi_no_select
  168.   ssi_no_#echo
  169.   ssi_no_#exec
  170.  
  171. 4) A sample "advanced options file"
  172.  
  173. The following is a sample of an advanced options file. You might also want
  174. to examine ADV_OPTS.CTL.
  175.  
  176. ;------------- Begin Example ------------
  177. ; call the sample external procedure
  178. exec adv_opts.cmd This is an argument , with commas embedded.
  179. ; 
  180. ; add a custom response header
  181. header add X-Webmaster-Name: Timothy Platypus
  182. ;
  183. ; Suppress headers, footers, and server side "excludes"
  184. ssi_no_header
  185. ssi_no_footer
  186. ssi_no_select
  187. ;------------- End Example ------------
  188.  
  189.  
  190.  
  191. ---- End of document
  192.